forgeos 0.1.0-alpha.7 → 0.1.0-alpha.71

package/src/forge/compiler/integration/templates/workos.ts

@@ -0,0 +1,1439 @@
+import type { IntegrationTemplateInput } from "./types.ts";
+import { buildDataGraph } from "../../data-graph/build.ts";
+
+const SECRETS_IMPORT = 'import type { SecretsContext } from "../secretsContext.js";';
+const CONFIG_IMPORT = 'import type { ConfigContext } from "../secretsContext.js";';
+
+const FALLBACK_PERMISSIONS = [
+  "onboarding:read",
+  "projects:manage",
+  "members:manage",
+  "invitations:create",
+  "tasks:manage",
+  "tasks:update",
+] as const;
+
+const FALLBACK_RESOURCE_TYPES = [
+  { slug: "organization", name: "Organization" },
+  { slug: "project", name: "Project", parent: "organization" },
+  { slug: "team", name: "Team", parent: "organization" },
+  { slug: "taskGroup", name: "Task Group", parent: "project" },
+  { slug: "task", name: "Task", parent: "project" },
+] as const;
+
+function quotedValues(text: string): string[] {
+  return [...text.matchAll(/["']([^"']+)["']/g)].map((match) => match[1]!).filter(Boolean);
+}
+
+function uniqueSorted(values: Iterable<string>): string[] {
+  return [...new Set([...values].filter(Boolean))].sort();
+}
+
+function toTitle(value: string): string {
+  return value
+    .replace(/[:._-]+/g, " ")
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+    .join(" ");
+}
+
+function policyNameForPermission(permission: string): string {
+  return permission.replace(/:/g, ".").replace(/[^a-zA-Z0-9_.-]+/g, ".");
+}
+
+function singularResourceName(name: string): string {
+  if (name.endsWith("ies")) return `${name.slice(0, -3)}y`;
+  if (name.endsWith("ses")) return name.slice(0, -2);
+  if (name.endsWith("s") && name.length > 1) return name.slice(0, -1);
+  return name;
+}
+
+function idFieldForResource(slug: string): string {
+  return `${slug.charAt(0).toLowerCase()}${slug.slice(1)}Id`;
+}
+
+function permissionsFromApp(input: IntegrationTemplateInput): string[] {
+  const permissions = new Set<string>();
+  for (const symbol of input.appGraph?.symbols ?? []) {
+    const sourceSlice = typeof symbol.meta.sourceSlice === "string" ? symbol.meta.sourceSlice : "";
+    for (const match of sourceSlice.matchAll(/canPermission\s*\(([^)]*)\)/g)) {
+      for (const value of quotedValues(match[1] ?? "")) {
+        permissions.add(value);
+      }
+    }
+  }
+  return permissions.size > 0 ? uniqueSorted(permissions) : [...FALLBACK_PERMISSIONS];
+}
+
+function resourceTypesFromApp(input: IntegrationTemplateInput): Array<{ slug: string; name: string; parent?: string }> {
+  if (!input.appGraph) {
+    return [...FALLBACK_RESOURCE_TYPES];
+  }
+  const dataGraph = buildDataGraph(input.appGraph);
+  const tenantTables = dataGraph.tables.filter((table) =>
+    table.fields.some((field) => field.name === "tenantId")
+  );
+  if (tenantTables.length === 0) {
+    return [...FALLBACK_RESOURCE_TYPES];
+  }
+  const resourceTypes = new Map<string, { slug: string; name: string; parent?: string }>();
+  resourceTypes.set("organization", { slug: "organization", name: "Organization" });
+  for (const table of tenantTables) {
+    if (["organization", "organizations", "membership", "memberships"].includes(table.name)) {
+      continue;
+    }
+    const slug = singularResourceName(table.name);
+    resourceTypes.set(slug, { slug, name: toTitle(slug), parent: "organization" });
+  }
+  for (const table of tenantTables) {
+    const slug = singularResourceName(table.name);
+    const current = resourceTypes.get(slug);
+    if (!current || slug === "organization") {
+      continue;
+    }
+    const parent = [...resourceTypes.keys()]
+      .filter((candidate) => candidate !== slug && candidate !== "organization")
+      .find((candidate) =>
+        table.fields.some((field) =>
+          field.name === idFieldForResource(candidate) ||
+          field.name === `${candidate}_id`
+        )
+      );
+    if (parent) {
+      resourceTypes.set(slug, { ...current, parent });
+    }
+  }
+  return [...resourceTypes.values()].sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
+function readPermissions(permissions: string[]): string[] {
+  return permissions.filter((permission) => /(^|:)read$|read|list|view/i.test(permission));
+}
+
+function updatePermissions(permissions: string[]): string[] {
+  return permissions.filter((permission) => /update|progress|write/i.test(permission));
+}
+
+function rolePermissions(permissions: string[]): Record<string, string[]> {
+  const member = uniqueSorted([...readPermissions(permissions), ...updatePermissions(permissions)]);
+  return {
+    owner: permissions,
+    manager: permissions,
+    member: member.length > 0 ? member : permissions.slice(0, 1),
+  };
+}
+
+function workosFgaEnabled(input: IntegrationTemplateInput): boolean {
+  return Boolean(
+    input.recipe.integrations?.includes("workos/fga.ts") ||
+      input.recipe.integrations?.includes("workos/resource-map.ts"),
+  );
+}
+
+export function renderWorkosServerAdapter(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated WorkOS server adapter — action/workflow/endpoint/server contexts only. */",
+    'import { createWorkOS, type WorkOS } from "@workos-inc/node";',
+    SECRETS_IMPORT,
+    CONFIG_IMPORT,
+    "",
+    "export interface ForgeWorkOSAuthKitConfig {",
+    "  apiKey: string;",
+    "  clientId: string;",
+    "  cookiePassword: string;",
+    "  redirectUri?: string;",
+    "  cookieName?: string;",
+    "  postLoginRedirectUri?: string;",
+    "  postLogoutRedirectUri?: string;",
+    "}",
+    "",
+    "export function createForgeWorkOS(secrets: SecretsContext): WorkOS {",
+    "  return createWorkOS({",
+    '    apiKey: secrets.get("WORKOS_API_KEY"),',
+    '    clientId: secrets.get("WORKOS_CLIENT_ID"),',
+    "  });",
+    "}",
+    "",
+    "export function resolveWorkOSAuthKitConfig(",
+    "  secrets: SecretsContext,",
+    "  config: ConfigContext,",
+    "): ForgeWorkOSAuthKitConfig {",
+    "  return {",
+    '    apiKey: secrets.get("WORKOS_API_KEY"),',
+    '    clientId: secrets.get("WORKOS_CLIENT_ID"),',
+    '    cookiePassword: secrets.get("WORKOS_COOKIE_PASSWORD"),',
+    '    redirectUri: config.optional("WORKOS_REDIRECT_URI"),',
+    '    cookieName: config.optional("WORKOS_COOKIE_NAME"),',
+    '    postLoginRedirectUri: config.optional("WORKOS_POST_LOGIN_REDIRECT_URI"),',
+    '    postLogoutRedirectUri: config.optional("WORKOS_POST_LOGOUT_REDIRECT_URI"),',
+    "  };",
+    "}",
+    "",
+    "export const forgeWorkOSRequiredClaims = {",
+    '  userId: "sub",',
+    '  tenantId: "organization_id",',
+    '  alternateTenantClaims: ["org_id", "tenant_id"],',
+    '  email: "email",',
+    '  organizationMembershipId: "organization_membership_id",',
+    '  role: "role",',
+    '  roles: "roles",',
+    '  permissions: "permissions",',
+    "} as const;",
+    "",
+  ].join("\n");
+}
+
+export function renderWorkosAuthkit(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated WorkOS AuthKit configuration notes. */",
+    "",
+    "export const workosAuthKitEnv = {",
+    '  mode: "oidc",',
+    '  apiKey: "WORKOS_API_KEY",',
+    '  clientId: "WORKOS_CLIENT_ID",',
+    '  cookiePassword: "WORKOS_COOKIE_PASSWORD",',
+    '  redirectUri: "WORKOS_REDIRECT_URI",',
+    '  cookieName: "WORKOS_COOKIE_NAME",',
+    '  postLoginRedirectUri: "WORKOS_POST_LOGIN_REDIRECT_URI",',
+    '  postLogoutRedirectUri: "WORKOS_POST_LOGOUT_REDIRECT_URI",',
+    '  issuer: "FORGE_AUTH_ISSUER",',
+    '  audience: "FORGE_AUTH_AUDIENCE",',
+    '  tenantClaim: "org_id",',
+    '  normalizedTenantClaim: "organization_id",',
+    '  emailClaim: "email",',
+    '  membershipClaim: "organization_membership_id",',
+    '  roleClaim: "role",',
+    '  permissionsClaim: "permissions",',
+    "} as const;",
+    "",
+    "export const workosAuthKitCommands = [",
+    '  "forge workos install --json",',
+    '  "forge workos install --yes --json",',
+    '  "forge workos doctor --json",',
+    '  "forge workos doctor --yes --json",',
+    '  "forge workos seed --file workos-seed.yml --dry-run --json",',
+    '  "forge workos seed --file workos-seed.yml --json",',
+    '  "forge workos prove --file workos-seed.yml --json",',
+    '  "forge workos setup --real --file workos-seed.yml --json",',
+    '  "forge auth check --json",',
+    '  "forge auth prove --json",',
+    "] as const;",
+    "",
+    "export const workosAuthKitRoutes = [",
+    '  { method: "GET", path: "/login", purpose: "start AuthKit login" },',
+    '  { method: "GET", path: "/callback", purpose: "exchange AuthKit code and set session cookie" },',
+    '  { method: "POST", path: "/logout", purpose: "clear local AuthKit session" },',
+    '  { method: "GET", path: "/session", purpose: "read the current Forge-normalized auth session" },',
+    "] as const;",
+    "",
+    "export function explainWorkOSProductionClaims(): string[] {",
+    "  return [",
+    '    "Use jwt or oidc auth mode in production; never dev-headers.",',
+    '    "Map the WorkOS organization claim to Forge organization_id consistently; org_id and tenant_id are accepted migration aliases.",',
+    '    "Include sub, email, organization_id, role, roles, permissions, and organization_membership_id in issued tokens.",',
+    '    "Include role, permissions, and organization_membership_id in the token when resource checks need them.",',
+    '    "Run tenant isolation tests with at least two organizations before public production.",',
+    "  ];",
+    "}",
+    "",
+  ].join("\n");
+}
+
+export function renderWorkosPolicies(input: IntegrationTemplateInput): string {
+  const permissions = permissionsFromApp(input);
+  return [
+    "/** Forge generated WorkOS-derived policy template.",
+    " * Import or merge these policies into src/policies.ts after reviewing names against your app.",
+    " */",
+    'import { canPermission, definePolicies } from "forge/policy";',
+    "",
+    "export const workosPermissionPolicies = definePolicies({",
+    ...permissions.map((permission) =>
+      `  "${policyNameForPermission(permission)}": canPermission("${permission}"),`
+    ),
+    "});",
+    "",
+    "export const workosPermissionPolicyMap = {",
+    ...permissions.map((permission) =>
+      `  "${permission}": "${policyNameForPermission(permission)}",`
+    ),
+    "} as const;",
+    "",
+  ].join("\n");
+}
+
+export function renderWorkosEnvExample(_input: IntegrationTemplateInput): string {
+  return [
+    "# Forge WorkOS/AuthKit production auth example.",
+    "# Secret values are intentionally blank. Keep real values in .env.local, your host secrets, or WorkOS/Vercel integration env.",
+    "FORGE_AUTH_MODE=oidc",
+    "FORGE_AUTH_ISSUER=https://api.workos.com",
+    "FORGE_AUTH_AUDIENCE=",
+    "# Set to https://api.workos.com/sso/jwks/<WORKOS_CLIENT_ID> after filling WORKOS_CLIENT_ID.",
+    "FORGE_AUTH_JWKS_URI=",
+    "FORGE_AUTH_ALGORITHMS=RS256",
+    "",
+    "WORKOS_API_KEY=",
+    "WORKOS_CLIENT_ID=",
+    "WORKOS_COOKIE_PASSWORD=",
+    "WORKOS_REDIRECT_URI=http://localhost:5173/callback",
+    "WORKOS_COOKIE_NAME=forgeos_workos_session",
+    "WORKOS_POST_LOGIN_REDIRECT_URI=http://localhost:5173/",
+    "WORKOS_POST_LOGOUT_REDIRECT_URI=http://localhost:5173/",
+    "WORKOS_WEBHOOK_SECRET=",
+    "",
+    "# Browser AuthKit settings for Vite/React. These are public client identifiers, not secrets.",
+    "VITE_FORGE_URL=http://localhost:3765",
+    "VITE_WORKOS_CLIENT_ID=",
+    "VITE_WORKOS_REDIRECT_URI=http://localhost:5173/callback",
+    "# Optional: map hosted WorkOS organization IDs to Forge tenant IDs when your app uses internal UUID tenants.",
+    "# VITE_FORGE_WORKOS_TENANT_MAP={\"org_...\":\"11111111-1111-4111-8111-111111111111\"}",
+    "# VITE_FORGE_WORKOS_TENANT_ID_FALLBACK=",
+    "",
+    "# WorkOS token claims expected by ForgeOS after forge add auth workos:",
+    "# sub, email, organization_id, role, roles, permissions, organization_membership_id",
+    "",
+  ].join("\n");
+}
+
+export function renderWorkosReactBridge(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated WorkOS/AuthKit React bridge.",
+    " * Import ForgeWorkOSAuthProvider from web/src/main.tsx, or copy the pattern into your app shell.",
+    " */",
+    'import { useEffect, useState, type ReactNode } from "react";',
+    'import { ForgeProvider, forgeUrl } from "./forge";',
+    "",
+    "const clientId = import.meta.env.VITE_WORKOS_CLIENT_ID as string | undefined;",
+    "const redirectUri = import.meta.env.VITE_WORKOS_REDIRECT_URI as string | undefined;",
+    "const forgeApiUrl = import.meta.env.VITE_FORGE_URL as string | undefined;",
+    "const workosTenantMap = import.meta.env.VITE_FORGE_WORKOS_TENANT_MAP as string | undefined;",
+    "const workosTenantFallback = import.meta.env.VITE_FORGE_WORKOS_TENANT_ID_FALLBACK as string | undefined;",
+    "",
+    "function workOSApiUrl(path: string): URL {",
+    "  if (typeof window !== 'undefined' && forgeApiUrl) {",
+    "    const configured = new URL(forgeApiUrl, window.location.origin);",
+    "    if ((configured.hostname === 'localhost' || configured.hostname === '127.0.0.1') && (window.location.hostname === 'localhost' || window.location.hostname === '127.0.0.1')) {",
+    "      return new URL(path, window.location.origin);",
+    "    }",
+    "  }",
+    "  return new URL(path, forgeApiUrl || forgeUrl || window.location.origin);",
+    "}",
+    "",
+    "export function hasWorkOSBrowserConfig(): boolean {",
+    "  return Boolean(clientId && redirectUri);",
+    "}",
+    "",
+    "function forgeTenantIdForWorkOSOrganization(claims: ForgeWorkOSBrowserSession['claims']) {",
+    "  if (!claims) {",
+    "    return undefined;",
+    "  }",
+    "  const explicitTenant = claims.tenant_id ?? claims.forge_tenant_id;",
+    "  if (explicitTenant) {",
+    "    return explicitTenant;",
+    "  }",
+    "  const organizationId = claims.organization_id;",
+    "  if (!organizationId) {",
+    "    return undefined;",
+    "  }",
+    "  if (workosTenantMap) {",
+    "    try {",
+    "      const parsed = JSON.parse(workosTenantMap) as Record<string, string>;",
+    "      if (parsed[organizationId]) {",
+    "        return parsed[organizationId];",
+    "      }",
+    "    } catch {",
+    "      // Keep authentication usable; forge workos doctor validates mapping syntax separately.",
+    "    }",
+    "  }",
+    "  if (organizationId.startsWith('org_') && workosTenantFallback) {",
+    "    return workosTenantFallback;",
+    "  }",
+    "  return organizationId;",
+    "}",
+    "",
+    "function workOSSessionToForgeAuth(session: ForgeWorkOSBrowserSession | null | undefined) {",
+    "  const claims = session?.claims;",
+    "  if (!claims?.sub) {",
+    "    return {};",
+    "  }",
+    "  const forgeTenantId = forgeTenantIdForWorkOSOrganization(claims);",
+    "  return {",
+    "    userId: claims.sub,",
+    "    tenantId: forgeTenantId,",
+    "    organizationId: forgeTenantId,",
+    "    organizationMembershipId: claims.organization_membership_id,",
+    "    role: claims.role ?? claims.roles?.[0],",
+    "    roles: claims.roles,",
+    "    permissions: claims.permissions,",
+    "    claims,",
+    "  };",
+    "}",
+    "",
+    "const workOSAuthProvider = async () => {",
+    "  const response = await fetch(workOSApiUrl('/session'), { credentials: 'include' });",
+    "  if (response.status === 401) {",
+    "    return {};",
+    "  }",
+    "  if (!response.ok) {",
+    "    throw new Error(`WorkOS session request failed with HTTP ${response.status}`);",
+    "  }",
+    "  const payload = await response.json() as { ok?: boolean; session?: ForgeWorkOSBrowserSession | null };",
+    "  return workOSSessionToForgeAuth(payload.ok ? payload.session ?? null : null);",
+    "};",
+    "",
+    "export function ForgeWorkOSAuthProvider({ children }: { children: ReactNode }) {",
+    "  if (!clientId || !redirectUri) {",
+    "    throw new Error(\"WorkOS AuthKit requires VITE_WORKOS_CLIENT_ID and VITE_WORKOS_REDIRECT_URI\");",
+    "  }",
+    "  return (",
+    "    <ForgeProvider url={forgeUrl} auth={workOSAuthProvider}>",
+    "      {children}",
+    "    </ForgeProvider>",
+    "  );",
+    "}",
+    "",
+    "export interface ForgeWorkOSBrowserSession {",
+    "  user?: { id?: string; email?: string; firstName?: string; lastName?: string };",
+    "  claims?: {",
+    "    sub?: string;",
+    "    email?: string;",
+    "    organization_id?: string;",
+    "    tenant_id?: string;",
+    "    forge_tenant_id?: string;",
+    "    organization_membership_id?: string;",
+    "    role?: string;",
+    "    roles?: string[];",
+    "    permissions?: string[];",
+    "  };",
+    "}",
+    "",
+    "export function useForgeWorkOSSession(): { loading: boolean; session: ForgeWorkOSBrowserSession | null; error: Error | null; refresh: () => Promise<void> } {",
+    "  const [loading, setLoading] = useState(true);",
+    "  const [session, setSession] = useState<ForgeWorkOSBrowserSession | null>(null);",
+    "  const [error, setError] = useState<Error | null>(null);",
+    "",
+    "  const refresh = async () => {",
+    "    setLoading(true);",
+    "    setError(null);",
+    "    try {",
+    "      const response = await fetch(workOSApiUrl('/session'), { credentials: 'include' });",
+    "      if (response.status === 401) {",
+    "        setSession(null);",
+    "        return;",
+    "      }",
+    "      if (!response.ok) {",
+    "        throw new Error(`WorkOS session request failed with HTTP ${response.status}`);",
+    "      }",
+    "      const payload = await response.json() as { ok?: boolean; session?: ForgeWorkOSBrowserSession | null };",
+    "      setSession(payload.ok ? payload.session ?? null : null);",
+    "    } catch (sessionError) {",
+    "      setSession(null);",
+    "      setError(sessionError instanceof Error ? sessionError : new Error('WorkOS session request failed'));",
+    "    } finally {",
+    "      setLoading(false);",
+    "    }",
+    "  };",
+    "",
+    "  useEffect(() => {",
+    "    void refresh();",
+    "  }, []);",
+    "",
+    "  return { loading, session, error, refresh };",
+    "}",
+    "",
+    "export function useWorkOSAuth() {",
+    "  const session = useForgeWorkOSSession();",
+    "  const user = session.session?.user ?? null;",
+    "  return {",
+    "    isLoading: session.loading,",
+    "    user,",
+    "    session: session.session,",
+    "    sessionError: session.error,",
+    "    refresh: session.refresh,",
+    "    signIn: () => {",
+    "      const url = workOSApiUrl('/login');",
+    "      url.searchParams.set('returnTo', window.location.pathname + window.location.search);",
+    "      window.location.assign(url);",
+    "    },",
+    "    signUp: () => {",
+    "      const url = workOSApiUrl('/login');",
+    "      url.searchParams.set('returnTo', window.location.pathname + window.location.search);",
+    "      window.location.assign(url);",
+    "    },",
+    "    signOut: () => { void fetch(workOSApiUrl('/logout'), { method: 'POST', credentials: 'include' }).finally(() => { window.location.assign('/'); }); },",
+    "    getAccessToken: async () => null,",
+    "  };",
+    "}",
+    "",
+    "export function WorkOSLoginPanel() {",
+    "  const { isLoading, user, signIn, signUp, signOut } = useWorkOSAuth();",
+    "  useEffect(() => {",
+    "    if (!isLoading && !user && window.location.pathname === \"/login\") {",
+    "      void signIn();",
+    "    }",
+    "  }, [isLoading, signIn, user]);",
+    "  if (isLoading) return <p>Loading authentication...</p>;",
+    "  if (!user && window.location.pathname === \"/login\") return <p>Redirecting...</p>;",
+    "  if (!user) {",
+    "    return (",
+    "      <div>",
+    "        <button type=\"button\" onClick={() => void signIn()}>Sign in</button>",
+    "        <button type=\"button\" onClick={() => void signUp()}>Sign up</button>",
+    "      </div>",
+    "    );",
+    "  }",
+    "  return (",
+    "    <div>",
+    "      <span>{user.email}</span>",
+    "      <button type=\"button\" onClick={() => signOut()}>Sign out</button>",
+    "    </div>",
+    "  );",
+    "}",
+    "",
+    "",
+  ].join("\n");
+}
+
+export function renderWorkosFga(input: IntegrationTemplateInput): string {
+  const permissions = permissionsFromApp(input);
+  const roles = rolePermissions(permissions);
+  const resourceTypes = resourceTypesFromApp(input);
+  return [
+    "/** Forge generated WorkOS FGA bridge helpers. */",
+    "",
+    "export const forgeWorkOSDefaultPermissions = [",
+    ...permissions.map((permission) => `  "${permission}",`),
+    "] as const;",
+    "",
+    "export type ForgeWorkOSPermission = (typeof forgeWorkOSDefaultPermissions)[number];",
+    "",
+    "export const forgeWorkOSDefaultRoles = {",
+    ...Object.entries(roles).map(([role, rolePerms]) =>
+      `  ${role}: [${rolePerms.map((permission) => `"${permission}"`).join(", ")}],`
+    ),
+    "} as const satisfies Record<string, readonly ForgeWorkOSPermission[]>;",
+    "",
+    "export const forgeWorkOSResourceTypes = [",
+    ...resourceTypes.map((resource) =>
+      `  { slug: "${resource.slug}",${resource.parent ? ` parent: "${resource.parent}",` : ""} description: "${resource.name} resource" },`
+    ),
+    "] as const;",
+    "",
+    "export interface ForgeWorkOSAccessCheckInput {",
+    "  organizationId: string;",
+    "  organizationMembershipId: string;",
+    "  permission: ForgeWorkOSPermission | string;",
+    "  resourceTypeSlug: string;",
+    "  resourceExternalId: string;",
+    "}",
+    "",
+    "export function buildWorkOSAccessCheck(input: ForgeWorkOSAccessCheckInput) {",
+    "  return {",
+    "    organizationMembershipId: input.organizationMembershipId,",
+    "    permissionSlug: input.permission,",
+    "    resourceTypeSlug: input.resourceTypeSlug,",
+    "    resourceExternalId: input.resourceExternalId,",
+    "  } as const;",
+    "}",
+    "",
+  ].join("\n");
+}
+
+export function renderWorkosResourceMap(input: IntegrationTemplateInput): string {
+  const resourceTypes = resourceTypesFromApp(input);
+  const helperResourceKinds = uniqueSorted([
+    "organization",
+    ...resourceTypes.map((resource) => resource.slug),
+    "project",
+    "team",
+    "taskGroup",
+    "task",
+  ]);
+  const resourceKindUnion = helperResourceKinds.map((resource) => `"${resource}"`).join(" | ");
+  return [
+    "/** Forge generated WorkOS FGA resource bridge.",
+    " * Keep calls to WorkOS Authorization API in server/action/workflow/endpoint contexts.",
+    " */",
+    "",
+    `export type ForgeWorkOSResourceKind = ${resourceKindUnion};`,
+    "export type ForgeWorkOSFgaFallback = \"deny\" | \"throw\";",
+    "",
+    "export interface ForgeWorkOSResourceRef {",
+    "  kind: ForgeWorkOSResourceKind;",
+    "  externalId: string;",
+    "  name?: string;",
+    "  description?: string;",
+    "  parent?: ForgeWorkOSResourceRef;",
+    "}",
+    "",
+    "export interface ForgeWorkOSApplicationGraph {",
+    "  organization: ForgeWorkOSResourceRef;",
+    "  resources: ForgeWorkOSResourceRef[];",
+    "  projects: ForgeWorkOSResourceRef[];",
+    "  teams: ForgeWorkOSResourceRef[];",
+    "  tasks: ForgeWorkOSResourceRef[];",
+    "}",
+    "",
+    "export interface ForgeWorkOSResourceRecord {",
+    "  organizationId: string;",
+    "  resourceTypeSlug: string;",
+    "  externalId: string;",
+    "  name: string;",
+    "  description?: string;",
+    "  parentResourceTypeSlug?: string;",
+    "  parentResourceExternalId?: string;",
+    "}",
+    "",
+    "function slug(value: string): string {",
+    "  return value.toLowerCase().replace(/[^a-z0-9]+/g, \"-\").replace(/^-+|-+$/g, \"\") || \"resource\";",
+    "}",
+    "",
+    "export function workosResource(kind: ForgeWorkOSResourceKind, id: string, parent?: ForgeWorkOSResourceRef, name?: string): ForgeWorkOSResourceRef {",
+    "  return { kind, externalId: `${kind}:${slug(id)}`, name: name ?? id, ...(parent ? { parent } : {}) };",
+    "}",
+    "",
+    "export function rootWorkOSResource(resource: ForgeWorkOSResourceRef): ForgeWorkOSResourceRef {",
+    "  let current = resource;",
+    "  while (current.parent) current = current.parent;",
+    "  return current;",
+    "}",
+    "",
+    "export function assertWorkOSResourceTenant(input: { resource: ForgeWorkOSResourceRef; organization: ForgeWorkOSResourceRef }): void {",
+    "  const root = rootWorkOSResource(input.resource);",
+    "  if (root.kind !== \"organization\" || root.externalId !== input.organization.externalId) {",
+    "    throw new Error(\"FORGE_WORKOS_CROSS_TENANT_RESOURCE: resource parent does not match organization\");",
+    "  }",
+    "}",
+    "",
+    "export function buildOnboardingResourceGraph(input: {",
+    "  organizationId: string;",
+    "  organizationName?: string;",
+    "  projects?: Array<string | { id: string; name?: string }>;",
+    "  teams?: Array<string | { id: string; name?: string }>;",
+    "  taskGroups?: Array<string | { id: string; name?: string; projectId?: string }>;",
+    "  tasks?: Array<string | { id: string; name?: string; projectId?: string }>;",
+    "}): ForgeWorkOSApplicationGraph {",
+    "  const organization = { kind: \"organization\", externalId: input.organizationId, name: input.organizationName ?? input.organizationId } satisfies ForgeWorkOSResourceRef;",
+    "  const normalize = (value: string | { id: string; name?: string }) => typeof value === \"string\" ? { id: value, name: value } : { id: value.id, name: value.name ?? value.id };",
+    "  const projects = (input.projects ?? []).map((value) => {",
+    "    const project = normalize(value);",
+    "    return workosResource(\"project\", project.id, organization, project.name);",
+    "  });",
+    "  const teams = (input.teams ?? []).map((value) => {",
+    "    const team = normalize(value);",
+    "    return workosResource(\"team\", team.id, organization, team.name);",
+    "  });",
+    "  const taskGroups = (input.taskGroups ?? []).map((value) => {",
+    "    const group = normalize(value);",
+    "    const projectId = typeof value === \"string\" ? undefined : value.projectId;",
+    "    const parent = projectId ? projects.find((project) => project.externalId === workosResource(\"project\", projectId, organization).externalId) ?? organization : organization;",
+    "    return workosResource(\"taskGroup\", group.id, parent, group.name);",
+    "  });",
+    "  const tasks = (input.tasks ?? []).map((value) => {",
+    "    const task = normalize(value);",
+    "    const projectId = typeof value === \"string\" ? undefined : value.projectId;",
+    "    const parent = projectId ? projects.find((project) => project.externalId === workosResource(\"project\", projectId, organization).externalId) ?? organization : organization;",
+    "    return workosResource(\"task\", task.id, parent, task.name);",
+    "  });",
+    "  const resources = [...projects, ...teams, ...taskGroups, ...tasks];",
+    "  return { organization, resources, projects, teams, tasks: [...taskGroups, ...tasks] };",
+    "}",
+    "",
+    "export interface ForgeWorkOSAuthorizationClient {",
+    "  authorization: {",
+    "    check(input: {",
+    "      organizationMembershipId: string;",
+    "      permissionSlug: string;",
+    "      resourceTypeSlug: string;",
+    "      resourceExternalId: string;",
+    "    }): Promise<{ authorized?: boolean; allowed?: boolean }>;",
+    "    createResource?(input: {",
+    "      organizationId: string;",
+    "      resourceTypeSlug: string;",
+    "      externalId: string;",
+    "      name: string;",
+    "      description?: string;",
+    "      parentResourceTypeSlug?: string;",
+    "      parentResourceExternalId?: string;",
+    "    }): Promise<unknown>;",
+    "    getResourceByExternalId?(input: { organizationId: string; resourceTypeSlug: string; externalId: string }): Promise<unknown>;",
+    "    updateResourceByExternalId?(input: { organizationId: string; resourceTypeSlug: string; externalId: string; name?: string; description?: string; parentResourceTypeSlug?: string; parentResourceExternalId?: string }): Promise<unknown>;",
+    "  };",
+    "}",
+    "",
+    "export interface ForgeWorkOSFgaTelemetry {",
+    "  emit?: (event: string, properties: Record<string, unknown>) => void | Promise<void>;",
+    "}",
+    "",
+    "export class ForgeWorkOSFgaDecisionCache {",
+    "  private entries = new Map<string, { allowed: boolean; expiresAt: number }>();",
+    "  constructor(private ttlMs = 30_000) {}",
+    "  key(input: { organizationMembershipId: string; permission: string; resource: ForgeWorkOSResourceRef }): string {",
+    "    return [input.organizationMembershipId, input.permission, input.resource.kind, input.resource.externalId].join(\"|\");",
+    "  }",
+    "  get(input: { organizationMembershipId: string; permission: string; resource: ForgeWorkOSResourceRef }): boolean | undefined {",
+    "    const entry = this.entries.get(this.key(input));",
+    "    if (!entry || entry.expiresAt < Date.now()) return undefined;",
+    "    return entry.allowed;",
+    "  }",
+    "  set(input: { organizationMembershipId: string; permission: string; resource: ForgeWorkOSResourceRef; allowed: boolean }): void {",
+    "    this.entries.set(this.key(input), { allowed: input.allowed, expiresAt: Date.now() + this.ttlMs });",
+    "  }",
+    "}",
+    "",
+    "function flattenResource(resource: ForgeWorkOSResourceRef): ForgeWorkOSResourceRef[] {",
+    "  const parent = resource.parent ? flattenResource(resource.parent) : [];",
+    "  return [...parent, resource];",
+    "}",
+    "",
+    "export function workOSResourceRecords(input: { organizationId: string; graph: ForgeWorkOSApplicationGraph }): ForgeWorkOSResourceRecord[] {",
+    "  const organization = input.graph.organization;",
+    "  const legacyResources = [...(input.graph.projects ?? []), ...(input.graph.teams ?? []), ...(input.graph.tasks ?? [])];",
+    "  const resources = [...(input.graph.resources ?? []), ...legacyResources]",
+    "    .flatMap((resource) => flattenResource(resource))",
+    "    .filter((resource) => resource.kind !== \"organization\");",
+    "  const byKey = new Map<string, ForgeWorkOSResourceRecord>();",
+    "  for (const resource of resources) {",
+    "    assertWorkOSResourceTenant({ resource, organization });",
+    "    byKey.set(`${resource.kind}:${resource.externalId}`, {",
+    "      organizationId: input.organizationId,",
+    "      resourceTypeSlug: resource.kind,",
+    "      externalId: resource.externalId,",
+    "      name: resource.name ?? resource.externalId,",
+    "      ...(resource.description ? { description: resource.description } : {}),",
+    "      ...(resource.parent && resource.parent.kind !== \"organization\" ? {",
+    "        parentResourceTypeSlug: resource.parent.kind,",
+    "        parentResourceExternalId: resource.parent.externalId,",
+    "      } : {}),",
+    "    });",
+    "  }",
+    "  return [...byKey.values()];",
+    "}",
+    "",
+    "export async function syncWorkOSResourceGraph(input: {",
+    "  client: ForgeWorkOSAuthorizationClient;",
+    "  organizationId: string;",
+    "  graph: ForgeWorkOSApplicationGraph;",
+    "  mode?: \"create\" | \"upsert\";",
+    "  telemetry?: ForgeWorkOSFgaTelemetry;",
+    "}): Promise<{ synced: number; created: number; updated: number; skipped: number; records: ForgeWorkOSResourceRecord[] }> {",
+    "  const records = workOSResourceRecords({ organizationId: input.organizationId, graph: input.graph });",
+    "  let created = 0;",
+    "  let updated = 0;",
+    "  let skipped = 0;",
+    "  for (const record of records) {",
+    "    if (!input.client.authorization.createResource) {",
+    "      skipped += 1;",
+    "      continue;",
+    "    }",
+    "    if (input.mode === \"upsert\" && input.client.authorization.getResourceByExternalId && input.client.authorization.updateResourceByExternalId) {",
+    "      try {",
+    "        await input.client.authorization.getResourceByExternalId({ organizationId: record.organizationId, resourceTypeSlug: record.resourceTypeSlug, externalId: record.externalId });",
+    "        await input.client.authorization.updateResourceByExternalId(record);",
+    "        updated += 1;",
+    "        await input.telemetry?.emit?.(\"forge.workos.fga.resource.updated\", { resourceTypeSlug: record.resourceTypeSlug, externalId: record.externalId });",
+    "        continue;",
+    "      } catch {",
+    "        // Missing resources fall through to create; other SDK/API errors surface from create.",
+    "      }",
+    "    }",
+    "    await input.client.authorization.createResource(record);",
+    "    created += 1;",
+    "    await input.telemetry?.emit?.(\"forge.workos.fga.resource.created\", { resourceTypeSlug: record.resourceTypeSlug, externalId: record.externalId });",
+    "  }",
+    "  return { synced: created + updated, created, updated, skipped, records };",
+    "}",
+    "",
+    "export async function canWorkOS(input: {",
+    "  client: ForgeWorkOSAuthorizationClient;",
+    "  organizationMembershipId: string;",
+    "  permission: string;",
+    "  resource: ForgeWorkOSResourceRef;",
+    "  organization?: ForgeWorkOSResourceRef;",
+    "  cache?: ForgeWorkOSFgaDecisionCache;",
+    "  telemetry?: ForgeWorkOSFgaTelemetry;",
+    "  fallback?: ForgeWorkOSFgaFallback;",
+    "}): Promise<boolean> {",
+    "  if (input.organization) {",
+    "    assertWorkOSResourceTenant({ resource: input.resource, organization: input.organization });",
+    "  }",
+    "  const cached = input.cache?.get(input);",
+    "  if (typeof cached === \"boolean\") {",
+    "    await input.telemetry?.emit?.(\"forge.workos.fga.cache_hit\", { permission: input.permission, resourceTypeSlug: input.resource.kind, resourceExternalId: input.resource.externalId, allowed: cached });",
+    "    return cached;",
+    "  }",
+    "  try {",
+    "    const result = await input.client.authorization.check({",
+    "      organizationMembershipId: input.organizationMembershipId,",
+    "      permissionSlug: input.permission,",
+    "      resourceTypeSlug: input.resource.kind,",
+    "      resourceExternalId: input.resource.externalId,",
+    "    });",
+    "    const allowed = Boolean(result.authorized ?? result.allowed);",
+    "    input.cache?.set({ ...input, allowed });",
+    "    await input.telemetry?.emit?.(\"forge.workos.fga.check\", { permission: input.permission, resourceTypeSlug: input.resource.kind, resourceExternalId: input.resource.externalId, allowed });",
+    "    return allowed;",
+    "  } catch (error) {",
+    "    await input.telemetry?.emit?.(\"forge.workos.fga.error\", { permission: input.permission, resourceTypeSlug: input.resource.kind, resourceExternalId: input.resource.externalId, error: error instanceof Error ? error.message : String(error) });",
+    "    if (input.fallback === \"deny\" || !input.fallback) return false;",
+    "    throw error;",
+    "  }",
+    "}",
+    "",
+  ].join("\n");
+}
+
+export function renderWorkosSession(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated WorkOS AuthKit session helpers. */",
+    'import type { ForgeWorkOSAuthKitConfig } from "../../packages/workos.server.js";',
+    "",
+    "export interface ForgeWorkOSSession {",
+    "  user: { id: string; email?: string; firstName?: string; lastName?: string; [key: string]: unknown };",
+    "  accessToken: string;",
+    "  refreshToken?: string;",
+    "  organizationId?: string;",
+    "  organizationMembershipId?: string;",
+    "  role?: string;",
+    "  roles?: string[];",
+    "  permissions?: string[];",
+    "  issuedAt: number;",
+    "}",
+    "",
+    "export interface ForgeWorkOSClaims {",
+    "  sub: string;",
+    "  email?: string;",
+    "  name?: string;",
+    "  organization_id?: string;",
+    "  organization_membership_id?: string;",
+    "  role?: string;",
+    "  roles?: string[];",
+    "  permissions?: string[];",
+    "}",
+    "",
+    "function bytesToBase64url(bytes: Uint8Array): string {",
+    "  let binary = \"\";",
+    "  for (const byte of bytes) binary += String.fromCharCode(byte);",
+    "  return btoa(binary).replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/g, \"\");",
+    "}",
+    "",
+    "function base64urlToBytes(input: string): Uint8Array {",
+    "  const padded = input.replace(/-/g, \"+\").replace(/_/g, \"/\").padEnd(Math.ceil(input.length / 4) * 4, \"=\");",
+    "  return Uint8Array.from(atob(padded), (char) => char.charCodeAt(0));",
+    "}",
+    "",
+    "function base64url(input: string): string {",
+    "  return bytesToBase64url(new TextEncoder().encode(input));",
+    "}",
+    "",
+    "function fromBase64url(input: string): string {",
+    "  return new TextDecoder().decode(base64urlToBytes(input));",
+    "}",
+    "",
+    "async function sign(payload: string, secret: string): Promise<string> {",
+    "  const key = await crypto.subtle.importKey(",
+    "    \"raw\",",
+    "    new TextEncoder().encode(secret),",
+    "    { name: \"HMAC\", hash: \"SHA-256\" },",
+    "    false,",
+    "    [\"sign\"],",
+    "  );",
+    "  const signature = await crypto.subtle.sign(\"HMAC\", key, new TextEncoder().encode(payload));",
+    "  return bytesToBase64url(new Uint8Array(signature));",
+    "}",
+    "",
+    "function safeEqual(a: string, b: string): boolean {",
+    "  if (a.length !== b.length) return false;",
+    "  let diff = 0;",
+    "  for (let index = 0; index < a.length; index += 1) diff |= a.charCodeAt(index) ^ b.charCodeAt(index);",
+    "  return diff === 0;",
+    "}",
+    "",
+    "export async function encodeWorkOSSession(session: ForgeWorkOSSession, cookiePassword: string): Promise<string> {",
+    "  const payload = base64url(JSON.stringify(session));",
+    "  return `${payload}.${await sign(payload, cookiePassword)}`;",
+    "}",
+    "",
+    "export async function decodeWorkOSSession(value: string | undefined, cookiePassword: string): Promise<ForgeWorkOSSession | null> {",
+    "  if (!value) return null;",
+    "  const [payload, signature] = value.split(\".\");",
+    "  if (!payload || !signature || !safeEqual(signature, await sign(payload, cookiePassword))) return null;",
+    "  return JSON.parse(fromBase64url(payload)) as ForgeWorkOSSession;",
+    "}",
+    "",
+    "export function readCookie(header: string | null | undefined, name: string): string | undefined {",
+    "  return (header ?? \"\")",
+    "    .split(\";\")",
+    "    .map((part) => part.trim())",
+    "    .find((part) => part.startsWith(`${name}=`))",
+    "    ?.slice(name.length + 1);",
+    "}",
+    "",
+    "export function sessionCookieName(config: ForgeWorkOSAuthKitConfig): string {",
+    "  return config.cookieName || \"forgeos_workos_session\";",
+    "}",
+    "",
+    "export async function createWorkOSSessionCookie(config: ForgeWorkOSAuthKitConfig, session: ForgeWorkOSSession): Promise<string> {",
+    "  const value = await encodeWorkOSSession(session, config.cookiePassword);",
+    "  return `${sessionCookieName(config)}=${value}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=2592000`;",
+    "}",
+    "",
+    "export function clearWorkOSSessionCookie(config: ForgeWorkOSAuthKitConfig): string {",
+    "  return `${sessionCookieName(config)}=; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=0`;",
+    "}",
+    "",
+    "export function workOSSessionToClaims(session: ForgeWorkOSSession): ForgeWorkOSClaims {",
+    "  return {",
+    "    sub: session.user.id,",
+    "    ...(session.user.email ? { email: String(session.user.email) } : {}),",
+    "    ...(session.user.firstName || session.user.lastName ? { name: [session.user.firstName, session.user.lastName].filter(Boolean).join(\" \") } : {}),",
+    "    ...(session.organizationId ? { organization_id: session.organizationId } : {}),",
+    "    ...(session.organizationMembershipId ? { organization_membership_id: session.organizationMembershipId } : {}),",
+    "    ...(session.role ? { role: session.role } : {}),",
+    "    ...(session.roles ? { roles: session.roles } : {}),",
+    "    ...(session.permissions ? { permissions: session.permissions } : {}),",
+    "  };",
+    "}",
+    "",
+  ].join("\n");
+}
+
+export function renderWorkosAuthRoutes(input: IntegrationTemplateInput): string {
+  const fallbackRolePermissions = rolePermissions(permissionsFromApp(input));
+  return [
+    "/** Forge generated framework-agnostic WorkOS AuthKit routes. */",
+    'import type { WorkOS } from "@workos-inc/node";',
+    'import type { ForgeWorkOSAuthKitConfig } from "../../packages/workos.server.js";',
+    'import { clearWorkOSSessionCookie, createWorkOSSessionCookie, decodeWorkOSSession, readCookie, sessionCookieName, workOSSessionToClaims, type ForgeWorkOSSession } from "./session.js";',
+    "",
+    "export interface WorkOSAuthRoutesOptions {",
+    "  workos: WorkOS;",
+    "  config: ForgeWorkOSAuthKitConfig;",
+    "  resolveOrganization?: (input: { user: Record<string, unknown>; accessToken: string; organizationId?: string; organizationMembershipId?: string; result: Record<string, unknown> }) => Promise<{ organizationId?: string; organizationMembershipId?: string; role?: string; roles?: string[]; permissions?: string[] }> | { organizationId?: string; organizationMembershipId?: string; role?: string; roles?: string[]; permissions?: string[] };",
+    "}",
+    "",
+    "function jsonResponse(body: unknown, status = 200, headers?: HeadersInit): Response {",
+    "  return new Response(JSON.stringify(body), { status, headers: { \"content-type\": \"application/json\", ...(headers ?? {}) } });",
+    "}",
+    "",
+    "function redirectResponse(location: string, headers?: HeadersInit): Response {",
+    "  return new Response(null, { status: 302, headers: { location, ...(headers ?? {}) } });",
+    "}",
+    "",
+    "function normalizeLocalRedirect(value: string | null | undefined, fallback = \"/\"): string {",
+    "  if (!value || !value.startsWith(\"/\") || value.startsWith(\"//\")) return fallback;",
+    "  return value;",
+    "}",
+    "",
+    "function workOSUserRecord(user: unknown): Record<string, unknown> {",
+    "  if (!user || typeof user !== \"object\") return {};",
+    "  return { ...(user as object) } as Record<string, unknown>;",
+    "}",
+    "",
+    "function workOSSessionUser(user: Record<string, unknown>): ForgeWorkOSSession[\"user\"] {",
+    "  const rawId = user.id ?? user.objectId ?? user.userId;",
+    "  return {",
+    "    ...user,",
+    "    id: typeof rawId === \"string\" && rawId.length > 0 ? rawId : String(rawId ?? \"workos-user\"),",
+    "    ...(typeof user.email === \"string\" ? { email: user.email } : {}),",
+    "    ...(typeof user.firstName === \"string\" ? { firstName: user.firstName } : {}),",
+    "    ...(typeof user.lastName === \"string\" ? { lastName: user.lastName } : {}),",
+    "  };",
+    "}",
+    "",
+    "const forgeWorkOSFallbackRolePermissions = {",
+    ...Object.entries(fallbackRolePermissions).map(([role, permissions]) =>
+      `  ${JSON.stringify(role)}: [${permissions.map((permission) => JSON.stringify(permission)).join(", ")}],`
+    ),
+    "} as const;",
+    "",
+    "function fallbackPermissionsForRole(role: string | undefined): string[] {",
+    "  if (!role) return [];",
+    "  const permissions = forgeWorkOSFallbackRolePermissions[role.toLowerCase() as keyof typeof forgeWorkOSFallbackRolePermissions];",
+    "  return permissions ? [...permissions] : [];",
+    "}",
+    "",
+    "export function getWorkOSAuthorizationUrl(input: { workos: WorkOS; config: ForgeWorkOSAuthKitConfig; state?: string }): string {",
+    "  if (!input.config.redirectUri) throw new Error(\"WORKOS_REDIRECT_URI is required\");",
+    "  const url = new URL(input.workos.userManagement.getAuthorizationUrl({",
+    "    provider: \"authkit\",",
+    "    redirectUri: input.config.redirectUri,",
+    "    clientId: input.config.clientId,",
+    "    ...(input.state ? { state: input.state } : {}),",
+    "  }));",
+    "  url.searchParams.set(\"response_type\", \"code\");",
+    "  url.searchParams.delete(\"organization_id\");",
+    "  return url.toString();",
+    "}",
+    "",
+    "export async function authenticateWorkOSCallback(input: { workos: WorkOS; config: ForgeWorkOSAuthKitConfig; code: string; resolveOrganization?: WorkOSAuthRoutesOptions[\"resolveOrganization\"] }): Promise<ForgeWorkOSSession> {",
+    "  const result = await input.workos.userManagement.authenticateWithCode({",
+    "    code: input.code,",
+    "    clientId: input.config.clientId,",
+    "  });",
+    "  const user = workOSUserRecord(result.user);",
+    "  const rawResult = result as unknown as Record<string, unknown>;",
+    "  const resultOrganization = (rawResult.organization ?? {}) as Record<string, unknown>;",
+    "  const resultMembership = (rawResult.organizationMembership ?? {}) as Record<string, unknown>;",
+    "  const resultOrganizationId = typeof rawResult.organizationId === \"string\" ? rawResult.organizationId : typeof resultOrganization.id === \"string\" ? resultOrganization.id : undefined;",
+    "  const resultOrganizationMembershipId = typeof rawResult.organizationMembershipId === \"string\" ? rawResult.organizationMembershipId : typeof resultMembership.id === \"string\" ? resultMembership.id : undefined;",
+    "  const resolved = await input.resolveOrganization?.({",
+    "    user,",
+    "    accessToken: result.accessToken,",
+    "    organizationId: resultOrganizationId,",
+    "    organizationMembershipId: resultOrganizationMembershipId,",
+    "    result: rawResult,",
+    "  });",
+    "  const resultRoles = Array.isArray(rawResult.roles) ? rawResult.roles.filter((role): role is string => typeof role === \"string\") : [];",
+    "  const resultPermissions = Array.isArray(rawResult.permissions) ? rawResult.permissions.filter((permission): permission is string => typeof permission === \"string\") : [];",
+    "  const organizationId = resolved?.organizationId ?? resultOrganizationId;",
+    "  const organizationMembershipId = resolved?.organizationMembershipId ?? resultOrganizationMembershipId;",
+    "  const role = resolved?.role ?? (typeof rawResult.role === \"string\" ? rawResult.role : resultRoles[0]);",
+    "  const roles = resolved?.roles ?? resultRoles;",
+    "  const permissions = resolved?.permissions ?? (resultPermissions.length > 0 ? resultPermissions : fallbackPermissionsForRole(role));",
+    "  return {",
+    "    user: workOSSessionUser(user),",
+    "    accessToken: result.accessToken,",
+    "    ...(result.refreshToken ? { refreshToken: result.refreshToken } : {}),",
+    "    ...(organizationId ? { organizationId } : {}),",
+    "    ...(organizationMembershipId ? { organizationMembershipId } : {}),",
+    "    ...(role ? { role } : {}),",
+    "    ...(roles.length > 0 ? { roles } : {}),",
+    "    ...(permissions.length > 0 ? { permissions } : {}),",
+    "    issuedAt: Math.floor(Date.now() / 1000),",
+    "  };",
+    "}",
+    "",
+    "export async function handleWorkOSAuthRequest(request: Request, options: WorkOSAuthRoutesOptions): Promise<Response> {",
+    "  const url = new URL(request.url);",
+    "  if (request.method === \"GET\" && url.pathname === \"/login\") {",
+    "    return redirectResponse(getWorkOSAuthorizationUrl({",
+    "      workos: options.workos,",
+    "      config: options.config,",
+    "      state: normalizeLocalRedirect(url.searchParams.get(\"returnTo\"), options.config.postLoginRedirectUri ?? \"/\"),",
+    "    }));",
+    "  }",
+    "  if (request.method === \"GET\" && url.pathname === \"/callback\") {",
+    "    const code = url.searchParams.get(\"code\");",
+    "    if (!code) return jsonResponse({ ok: false, error: \"missing_code\" }, 400);",
+    "    const session = await authenticateWorkOSCallback({",
+    "      workos: options.workos,",
+    "      config: options.config,",
+    "      code,",
+    "      resolveOrganization: options.resolveOrganization,",
+    "    });",
+    "    const location = normalizeLocalRedirect(url.searchParams.get(\"state\"), options.config.postLoginRedirectUri || \"/\");",
+    "    return redirectResponse(location, { \"set-cookie\": await createWorkOSSessionCookie(options.config, session) });",
+    "  }",
+    "  if (request.method === \"POST\" && url.pathname === \"/logout\") {",
+    "    return redirectResponse(normalizeLocalRedirect(options.config.postLogoutRedirectUri, \"/\"), { \"set-cookie\": clearWorkOSSessionCookie(options.config) });",
+    "  }",
+    "  if (request.method === \"GET\" && url.pathname === \"/session\") {",
+    "    const session = await decodeWorkOSSession(readCookie(request.headers.get(\"cookie\"), sessionCookieName(options.config)), options.config.cookiePassword);",
+    "    return session ? jsonResponse({ ok: true, session: { user: session.user, claims: workOSSessionToClaims(session) } }) : jsonResponse({ ok: false, session: null }, 401);",
+    "  }",
+    "  return jsonResponse({ ok: false, error: \"not_found\" }, 404);",
+    "}",
+    "",
+    "export const workosAuthHttpRoutes = [",
+    '  { method: "GET", path: "/login" },',
+    '  { method: "GET", path: "/callback" },',
+    '  { method: "POST", path: "/logout" },',
+    '  { method: "GET", path: "/session" },',
+    "] as const;",
+    "",
+  ].join("\n");
+}
+
+export function renderWorkosHttpHandler(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated WorkOS webhook HTTP handler.",
+    " * Mount this handler at POST /webhooks/workos in your web/server framework.",
+    " */",
+    "import { handleWorkOSWebhook, type WorkOSWebhookEvent, type WorkOSWebhookVerificationInput } from \"./webhook.js\";",
+    "",
+    "export interface WorkOSWebhookHttpHandlerOptions extends Pick<WorkOSWebhookVerificationInput, \"secrets\" | \"replayStore\" | \"nowSeconds\" | \"toleranceSeconds\"> {",
+    "  onEvent?: (event: WorkOSWebhookEvent) => Promise<void> | void;",
+    "}",
+    "",
+    "function jsonResponse(body: unknown, status: number): Response {",
+    "  return new Response(JSON.stringify(body), {",
+    "    status,",
+    "    headers: { \"content-type\": \"application/json\" },",
+    "  });",
+    "}",
+    "",
+    "export async function handleWorkOSWebhookRequest(request: Request, options: WorkOSWebhookHttpHandlerOptions): Promise<Response> {",
+    "  if (request.method !== \"POST\") {",
+    "    return jsonResponse({ ok: false, error: \"method_not_allowed\" }, 405);",
+    "  }",
+    "  const payload = await request.text();",
+    "  const result = await handleWorkOSWebhook({",
+    "    payload,",
+    "    signatureHeader: request.headers.get(\"WorkOS-Signature\"),",
+    "    secrets: options.secrets,",
+    "    replayStore: options.replayStore,",
+    "    nowSeconds: options.nowSeconds,",
+    "    toleranceSeconds: options.toleranceSeconds,",
+    "  });",
+    "  if (result.status !== 200 || !result.event) {",
+    "    return jsonResponse({ ok: false, error: result.error ?? \"invalid_workos_webhook\" }, 401);",
+    "  }",
+    "  await options.onEvent?.(result.event);",
+    "  return jsonResponse({ ok: true, event: result.event.event ?? \"unknown\" }, 200);",
+    "}",
+    "",
+    "export const workosWebhookHttpRoute = {",
+    "  method: \"POST\",",
+    "  path: \"/webhooks/workos\",",
+    "  handler: \"handleWorkOSWebhookRequest\",",
+    "  signatureHeader: \"WorkOS-Signature\",",
+    "} as const;",
+    "",
+  ].join("\n");
+}
+
+export function renderWorkosWebhook(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated WorkOS webhook verification and endpoint helper. */",
+    'import { verifyWebhookSignature, type WebhookReplayStore } from "forge/server";',
+    'import type { SecretsContext } from "../../secretsContext.js";',
+    "",
+    "export interface WorkOSWebhookEvent {",
+    "  id?: string;",
+    "  event?: string;",
+    "  data?: unknown;",
+    "  created_at?: string;",
+    "  context?: Record<string, unknown>;",
+    "}",
+    "",
+    "export interface WorkOSWebhookVerificationInput {",
+    "  payload: string | Uint8Array;",
+    "  signatureHeader: string | null | undefined;",
+    "  secrets: SecretsContext;",
+    "  eventId?: string;",
+    "  replayStore?: WebhookReplayStore;",
+    "  nowSeconds?: number;",
+    "  toleranceSeconds?: number;",
+    "}",
+    "",
+    "function bodyString(input: string | Uint8Array): string {",
+    '  return typeof input === "string" ? input : new TextDecoder().decode(input);',
+    "}",
+    "",
+    "export async function verifyWorkOSWebhook(input: WorkOSWebhookVerificationInput): Promise<WorkOSWebhookEvent> {",
+    '  const secret = input.secrets.get("WORKOS_WEBHOOK_SECRET");',
+    '  if (!secret) throw new Error("WORKOS_WEBHOOK_SECRET is required");',
+    "  const verified = await verifyWebhookSignature({",
+    '    provider: "workos",',
+    "    secret,",
+    "    payload: input.payload,",
+    "    signatureHeader: input.signatureHeader,",
+    "    eventId: input.eventId,",
+    "    replayStore: input.replayStore,",
+    "    nowSeconds: input.nowSeconds,",
+    "    toleranceSeconds: input.toleranceSeconds,",
+    "  });",
+    '  if (!verified.ok) throw new Error(`${verified.code}: ${verified.reason}`);',
+    "  return JSON.parse(bodyString(input.payload)) as WorkOSWebhookEvent;",
+    "}",
+    "",
+    "export async function handleWorkOSWebhook(input: WorkOSWebhookVerificationInput): Promise<{ status: 200 | 401; event?: WorkOSWebhookEvent; error?: string }> {",
+    "  try {",
+    "    const event = await verifyWorkOSWebhook(input);",
+    "    return { status: 200, event };",
+    "  } catch (error) {",
+    "    return { status: 401, error: error instanceof Error ? error.message : String(error) };",
+    "  }",
+    "}",
+    "",
+    "export const workosWebhookEndpoint = {",
+    '  method: "POST",',
+    '  path: "/webhooks/workos",',
+    '  signatureHeader: "WorkOS-Signature",',
+    '  secret: "WORKOS_WEBHOOK_SECRET",',
+    "} as const;",
+    "",
+  ].join("\n");
+}
+
+export function renderWorkosSeed(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated WorkOS seed metadata. */",
+    "",
+    "export const workosSeedFile = \"workos-seed.yml\" as const;",
+    "",
+    "export const workosSeedCommands = [",
+    "  `npx workos@latest seed --file ${workosSeedFile}`,",
+    "  `npx workos@latest seed --file ${workosSeedFile} --clean`,",
+    "] as const;",
+    "",
+    "export const workosSeedStateFile = \".workos-seed-state.json\" as const;",
+    "",
+  ].join("\n");
+}
+
+export function renderWorkosSeedYaml(input: IntegrationTemplateInput): string {
+  const permissions = permissionsFromApp(input);
+  const roles = rolePermissions(permissions);
+  const resourceTypes = workosFgaEnabled(input) ? resourceTypesFromApp(input) : [];
+  const resourceTypeSection = resourceTypes.length > 0
+    ? [
+        "",
+        "resource_types:",
+        ...resourceTypes.flatMap((resource) => [
+          `  - slug: '${resource.slug}'`,
+          `    name: '${resource.name}'`,
+          ...(resource.parent ? [`    parent: '${resource.parent}'`] : []),
+        ]),
+      ]
+    : [];
+  return [
+    "# Forge generated WorkOS seed file.",
+    "# Review names, domains, redirect URIs, and origins before applying to a real WorkOS environment.",
+    "permissions:",
+    ...permissions.flatMap((permission) => [
+      `  - name: '${toTitle(permission)}'`,
+      `    slug: '${permission}'`,
+    ]),
+    ...resourceTypeSection,
+    "",
+    "roles:",
+    ...Object.entries(roles).flatMap(([role, rolePermissions]) => [
+      `  - name: '${toTitle(role)}'`,
+      `    slug: '${role}'`,
+      "    permissions:",
+      ...rolePermissions.map((permission) => `      - '${permission}'`),
+    ]),
+    "",
+    "organizations:",
+    "  - name: 'Acme Corp'",
+    "    domains: ['acme.test']",
+    "  - name: 'Globex'",
+    "    domains: ['globex.test']",
+    "",
+    "config:",
+    "  redirect_uris:",
+    "    - 'http://localhost:5173'",
+    "    - 'http://localhost:5173/callback'",
+    "    - 'http://127.0.0.1:5173'",
+    "    - 'http://127.0.0.1:5173/callback'",
+    "  cors_origins:",
+    "    - 'http://localhost:5173'",
+    "    - 'http://127.0.0.1:5173'",
+    "  homepage_url: 'http://localhost:5173'",
+    "  webhook_endpoints:",
+    "    - url: 'http://localhost:3765/webhooks/workos'",
+    "      events:",
+    "        - 'authentication.succeeded'",
+    "        - 'organization_membership.created'",
+    "        - 'organization_membership.updated'",
+    "        - 'organization_membership.deleted'",
+    "",
+  ].join("\n");
+}
+
+export function renderWorkosTestkit(input: IntegrationTemplateInput): string {
+  const permissions = permissionsFromApp(input);
+  const roles = rolePermissions(permissions);
+  const ownerPermissions = JSON.stringify(roles.owner);
+  const managerPermissions = JSON.stringify(roles.manager);
+  const memberPermissions = JSON.stringify(roles.member);
+  return [
+    "/** Forge generated mock testkit for WorkOS auth and authorization. */",
+    "",
+    "type Resource = { organizationId: string; resourceTypeSlug: string; externalId: string; name: string; parentResourceTypeSlug?: string; parentResourceExternalId?: string };",
+    "type Membership = { id: string; organizationId: string; roleSlug: string; permissions: string[] };",
+    "type RoleAssignment = { organizationMembershipId: string; roleSlug: string; resourceTypeSlug: string; resourceExternalId: string; permissions: string[] };",
+    "",
+    "export function createWorkOSMock() {",
+    "  const organizations = new Map<string, { id: string; name: string }>();",
+    "  organizations.set(\"org_acme\", { id: \"org_acme\", name: \"Acme Corp\" });",
+    "  organizations.set(\"org_globex\", { id: \"org_globex\", name: \"Globex\" });",
+    "  const memberships = new Map<string, Membership>([",
+    `    ["om_acme_owner", { id: "om_acme_owner", organizationId: "org_acme", roleSlug: "owner", permissions: ${ownerPermissions} }],`,
+    `    ["om_acme_member", { id: "om_acme_member", organizationId: "org_acme", roleSlug: "member", permissions: ${memberPermissions} }],`,
+    `    ["om_globex_member", { id: "om_globex_member", organizationId: "org_globex", roleSlug: "member", permissions: ${memberPermissions} }],`,
+    "  ]);",
+    "  const resources = new Map<string, Resource>();",
+    "  const roleAssignments: RoleAssignment[] = [];",
+    "  const accessChecks: Array<{ organizationMembershipId: string; permissionSlug: string; resourceTypeSlug: string; resourceExternalId: string; authorized: boolean; reason: string }> = [];",
+    "  const key = (organizationId: string, resourceTypeSlug: string, externalId: string) => `${organizationId}|${resourceTypeSlug}|${externalId}`;",
+    "  const resourceOrg = (resourceTypeSlug: string, resourceExternalId: string): string | undefined => {",
+    "    for (const resource of resources.values()) {",
+    "      if (resource.resourceTypeSlug === resourceTypeSlug && resource.externalId === resourceExternalId) return resource.organizationId;",
+    "    }",
+    "    return undefined;",
+    "  };",
+    "  return {",
+    "    organizations: {",
+    "      createOrganization: async (input: { name: string; externalId?: string }) => {",
+    "        const id = input.externalId ?? `org_${organizations.size + 1}`;",
+    "        const organization = { id, name: input.name };",
+    "        organizations.set(id, organization);",
+    "        return organization;",
+    "      },",
+    "      listOrganizations: async () => ({ data: [...organizations.values()] }),",
+    "    },",
+    "    userManagement: {",
+    "      createOrganizationMembership: async (input: { organizationId: string; roleSlug: string; userId?: string }) => {",
+    "        const id = `om_${input.organizationId}_${memberships.size + 1}`;",
+    `        const permissions = input.roleSlug === "owner" ? ${ownerPermissions} : input.roleSlug === "manager" ? ${managerPermissions} : ${memberPermissions};`,
+    "        const membership = { id, organizationId: input.organizationId, roleSlug: input.roleSlug, permissions };",
+    "        memberships.set(id, membership);",
+    "        return membership;",
+    "      },",
+    "    },",
+    "    authorization: {",
+    "      createResource: async (input: Resource) => {",
+    "        resources.set(key(input.organizationId, input.resourceTypeSlug, input.externalId), input);",
+    "        return { id: `authz_resource_${resources.size}`, ...input };",
+    "      },",
+    "      getResourceByExternalId: async (input: { organizationId: string; resourceTypeSlug: string; externalId: string }) => {",
+    "        const resource = resources.get(key(input.organizationId, input.resourceTypeSlug, input.externalId));",
+    "        if (!resource) throw new Error(\"resource_not_found\");",
+    "        return { id: `authz_resource_${input.externalId}`, ...resource };",
+    "      },",
+    "      updateResourceByExternalId: async (input: Resource) => {",
+    "        resources.set(key(input.organizationId, input.resourceTypeSlug, input.externalId), input);",
+    "        return { id: `authz_resource_${input.externalId}`, ...input };",
+    "      },",
+    "      assignRole: async (input: { organizationMembershipId: string; roleSlug: string; resourceTypeSlug: string; resourceExternalId: string; permissions?: string[] }) => {",
+    "        const assignment = { organizationMembershipId: input.organizationMembershipId, roleSlug: input.roleSlug, resourceTypeSlug: input.resourceTypeSlug, resourceExternalId: input.resourceExternalId, permissions: input.permissions ?? [] };",
+    "        roleAssignments.push(assignment);",
+    "        return assignment;",
+    "      },",
+    "      check: async (input: { organizationMembershipId: string; permissionSlug: string; resourceTypeSlug: string; resourceExternalId: string }) => {",
+    "        const membership = memberships.get(input.organizationMembershipId);",
+    "        const organizationId = resourceOrg(input.resourceTypeSlug, input.resourceExternalId);",
+    "        const sameTenant = Boolean(membership && organizationId && membership.organizationId === organizationId);",
+    "        const direct = Boolean(membership?.permissions.includes(input.permissionSlug));",
+    "        const assigned = roleAssignments.some((assignment) => assignment.organizationMembershipId === input.organizationMembershipId && assignment.resourceTypeSlug === input.resourceTypeSlug && assignment.resourceExternalId === input.resourceExternalId && assignment.permissions.includes(input.permissionSlug));",
+    "        const authorized = sameTenant && (direct || assigned);",
+    "        accessChecks.push({",
+    "          organizationMembershipId: input.organizationMembershipId,",
+    "          permissionSlug: input.permissionSlug,",
+    "          resourceTypeSlug: input.resourceTypeSlug,",
+    "          resourceExternalId: input.resourceExternalId,",
+    "          authorized,",
+    "          reason: sameTenant ? \"permission\" : \"cross_tenant\",",
+    "        });",
+    "        return { authorized };",
+    "      },",
+    "    },",
+    "    getResources: () => [...resources.values()],",
+    "    getMemberships: () => [...memberships.values()],",
+    "    getRoleAssignments: () => [...roleAssignments],",
+    "    getAccessChecks: () => [...accessChecks],",
+    "  } as const;",
+    "}",
+    "",
+  ].join("\n");
+}
+
+export function renderWorkosDoc(input: IntegrationTemplateInput): string {
+  const fgaEnabled = workosFgaEnabled(input);
+  const fgaCommandLines = fgaEnabled
+    ? [
+        "forge workos fga plan --file workos-seed.yml --write --json",
+        "forge workos fga sync --file workos-seed.yml --json",
+        "forge workos fga prove --file workos-seed.yml --json",
+      ]
+    : [
+        "# Optional when resource-level WorkOS Authorization is required:",
+        "forge add auth workos --with-fga",
+      ];
+  const fgaSection = fgaEnabled
+    ? [
+        "## FGA strategy",
+        "",
+        "Use JWT permissions for organization-wide checks. Use the WorkOS Authorization API for resource-level checks such as project, workspace, or task access. Keep those API calls in actions, workflows, endpoints, or server code; commands and queries should consume validated auth/policy context rather than importing the WorkOS SDK.",
+        "",
+        "Use `syncWorkOSResourceGraph(...)` after app resources are created or renamed to mirror the Forge resource graph into WorkOS FGA resources. Use `canWorkOS(...)` with `ForgeWorkOSFgaDecisionCache` for resource-level checks; it calls WorkOS `authorization.check` with `organizationMembershipId`, `permissionSlug`, `resourceTypeSlug`, and `resourceExternalId`, emits optional telemetry, and denies by default on provider errors unless `fallback: \"throw\"` is set.",
+        "",
+        "Use `assertWorkOSResourceTenant(...)` before resource-level FGA checks whenever the resource came from user input or an external id. This keeps Acme resources from being checked under Globex membership context.",
+      ]
+    : [
+        "## Authorization strategy",
+        "",
+        "The default WorkOS recipe uses AuthKit, organization claims, roles, permissions, Forge policies, and tenant isolation. That is enough for most SaaS apps.",
+        "",
+        "FGA is optional. Add it only when your app needs resource-level authorization beyond organization roles and permission claims, for example per-project, per-document, or inherited resource access.",
+      ];
+  return [
+    "# WorkOS integration",
+    "",
+    "Generated by Forge (recipe v1).",
+    "",
+    "WorkOS is the preferred ForgeOS auth adapter for B2B, organization-scoped, agent-operable authentication and authorization.",
+    "",
+    "## What this recipe does",
+    "",
+    "- Installs `@workos-inc/node` for server/action/workflow/endpoint code.",
+    "- Installs `@workos-inc/authkit-react` and generates a Vite React bridge when a `web/package.json` workspace exists.",
+    "- Registers WorkOS secret names without storing values.",
+    "- Generates an AuthKit/RBAC checklist and a `workos-seed.yml` for roles, permissions, organizations, redirect URIs, and CORS origins.",
+    ...(fgaEnabled ? ["- Generates optional WorkOS FGA resource graph helpers and resource type seed metadata."] : []),
+    "- Generates framework-agnostic AuthKit route/session helpers for `/login`, `/callback`, `/logout`, and `/session`.",
+    "- Generates a framework-agnostic `Request -> Response` webhook handler for `POST /webhooks/workos`.",
+    "- Marks WorkOS SDK imports as forbidden from commands, queries, liveQueries, client, shared, and edge code.",
+    "",
+    "## Commands",
+    "",
+    "```bash",
+    "forge add auth workos",
+    "forge workos install --yes --json",
+    "forge workos doctor --json",
+    "forge workos doctor --yes --json",
+    "forge workos seed --file workos-seed.yml --dry-run --json",
+    "forge workos seed --file workos-seed.yml --json",
+    "forge workos prove --file workos-seed.yml --json",
+    "forge workos setup --real --file workos-seed.yml --json",
+    ...fgaCommandLines,
+    "forge auth check --json",
+    "forge auth prove --json",
+    "forge check --json",
+    "```",
+    "",
+    "## Required environment names",
+    "",
+    ...input.secrets
+      .filter((secret) => secret.required !== false)
+      .map((secret) => `- \`${secret.envVar}\``),
+    "",
+    "## Optional environment names",
+    "",
+    ...input.secrets
+      .filter((secret) => secret.required === false)
+      .map((secret) => `- \`${secret.envVar}\``),
+    "",
+    "## Production auth mapping",
+    "",
+    "- `FORGE_AUTH_MODE=oidc` or `jwt`",
+    "- `FORGE_AUTH_ISSUER=https://api.workos.com` for hosted WorkOS AuthKit.",
+    "- `FORGE_AUTH_JWKS_URI=https://api.workos.com/sso/jwks/<WORKOS_CLIENT_ID>` for hosted WorkOS AuthKit.",
+    "- `FORGE_AUTH_AUDIENCE` matches the API audience configured for the app.",
+    "- Tenant claim should map to WorkOS `org_id` or a normalized `tenant_id` claim.",
+    "- Role and permissions should come from WorkOS organization roles/permissions, not from dev headers.",
+    "- Use generated `src/policies.workos.ts` as a permission-first policy template; it uses `canPermission(...)` rather than role-only checks.",
+    "- `dev-headers` and frontend `devAuth` are local-only simulation paths. Real WorkOS production-like tests should use AuthKit and Bearer tokens.",
+    "",
+    "## AuthKit routes",
+    "",
+    "Mount `handleWorkOSAuthRequest(request, { workos, config, resolveOrganization })` for `/login`, `/callback`, `/logout`, and `/session`. The callback exchanges the AuthKit authorization code, signs an HttpOnly session cookie, and exposes Forge-normalized claims through `/session`.",
+    "",
+    ...fgaSection,
+    "",
+    "## Webhook route",
+    "",
+    "Mount `handleWorkOSWebhookRequest(request, { secrets, replayStore, onEvent })` at `POST /webhooks/workos`. The handler verifies `WorkOS-Signature`, rejects stale/replayed/tampered events, and returns JSON responses.",
+    "",
+    `Compatible contexts: ${input.compatible.join(", ")}`,
+    "",
+    `Incompatible contexts: ${input.incompatible.join(", ")}`,
+    "",
+  ].join("\n");
+}